What's it all for?



Most Java developers are familiar with the power of Ant for writing build scripts, deployment scripts and sundry other tasks. Antigen wraps up an Ant script as an executable jar file and combines it with a user-friendly GUI.

The most obvious application is to use Antigen to create Installers. You write an Ant script to install your application, using the <input> task to prompt the user for configuration settings such as installation location, write a small properties file setting up window titles, icons etc and then run Antigen to wrap the whole lot up as an executable jar file.

When you're finished, you have a GUI based installer such as the one on the right. The end-user does not need Ant on their machine to use it, just Java.



Using Antigen

Antigen can be used to wrap your Ant script in two ways. The quickest way to get started is to use the Antigen tool (see QuickStart). Alternatively, you can include the Antigen jar file (known as Antibody) in your build process - this is particularly easy to do if you're using Maven to build your application.

Quick Start

If you have your Ant build.xml ready, this will take a few seconds.
  1. Debug your Ant script first! It's a lot quicker doing this on the commandline than when it's already wrapped up in Antigen
  2. Download and execute Antigen. While you are waiting...
  3. Place the build.xml and any files the Ant script needs (such as property files) into a folder (e.g. called ant)
  4. Optional: create a configuration file called config.properties in another folder (e.g. called resources)
    • For a very simple installer, config.properties can be empty. To jazz it up a bit, see Configuration options
  5. Antigen will pop up an info screen, and then ask you to select the tasks you wish to run. If you have prepared a custom config.properties file, then check the "Customize your Installer" box.
  6. The Antigen app will prompt you for the name of your project, and the name of the installer you wish to create
  7. Since Antigen wraps up Ant and various other libraries, the resulting installer can get quite large. Antigen will give you the option to remove stuff you don't use. If you're not using any of the optional Ant tasks, or you don't have intro or outtro pages (see Intro Pages), you can cut the size of the installer in half by telling Antigen to omit the irrelevant libraries.
  8. Finally Antigen will prompt your for the names of the folder(s) you created earlier
If all goes well, it should have created an executable jar for you. Unless you specified otherwise in the config double-clicking on this jar file should execute your script's default target.

Problems

Debugging

The easiest way to debug is to run your installer from the commandline with java -jar installer.jar - debug information will be echoed to the console. For extra debug information use the -d switch.

More advanced...

Configuration options

Trying to keep pace with the number of options is probably futile, so here is a link to the latest config.properties file in cvs, which should be documented well enough to work things out.

The main things to note are:

Location of logos and other resources

Logos and other resources should be placed under the folder containing the config.properties file. Thus, to set the top right logo and the intro text you place entries in the config.properties file of

antigen.logo.right=img/logo.jpg

antigen.intro.template=velocitytemplates/hello.html

and have a directory structure 

.
`-- resources
    |-- img
    |   |
    |   `-- logo.jpg
    |-- velocitytemplates
    |   |   
    |   `-- hello.html
    `-- config.properties

Setting the Ant target(s) you wish to execute



  By default (!) the default target in your build file is executed. Alternatively, you can specify the target(s) in the config.properties file. If you specify more than one target (as a comma-separated list), then the user will be presented with with a list of check boxes to determine which targets to run. You can configure some checkboxes to be unchecked by default. Antigen will run the targets in the order they are listed, and ant properties are inherited from one to the next. This is useful since users will not be prompted twice for the same input property.



Intro and Outtro pages and Velocity Templates

You can specify text to be shown to the user before and after the installation process. This is quite handy for warning him or her what is about to happen! You can either specify the text in the property file, or provide a reference to a text file (see Location of logos and other resources). In both cases the text supplied should be html formatted. In the latter case, the text is always processed by Velocity (and therefore the velocity library must not be excluded from the installer if this feature is used!). This is very powerful, and allows you to interpolate ant properties in your text, and show text conditionally based in property settings. Note, that velocity does not allow properties to include a period as part of their name, so these are replaced with underscores in the velocity engine. Thus if your ant file includes a task

<input addproperty="your.name">Enter your name</input>

then in your outtro text you can do things like: 

        Goodbye $your_name!

Prompting the user for input

Any <input/> tags in your buildfile will cause a dialog box to be opened to prompt the user for input. The exact form of this dialog depends on a number of things. If the validargs attribute has been set to restrict the user input, then the dialog will have radio buttons for the user to select. If you wish the user to enter a file name or dir name, then it is possible to configure antigen to recognise certain property suffices such as .file or .dir as representing files and directories, and the dialog box will include a browse button to allow the user to select the file from their file system. In all cases the dialog boxes are prepopulated with the contents of the defaultvalue attribute, if present. As is standard practice in Ant 1.6+, if a property is already set, then the input task will be skipped.

Command-line options

Antigen has a number of options that can be specified on the commandline. To view them type

java -jar myinstaller.jar -h

These options include increasing the debug logging output for when your installer isn't working as it ought to, and running the installer in a text-only environment.

Using Antibody as part of a Maven build

Coming soon....in the meantime, you should be able to work out how to do it from looking at the build of Antigen itself....Antigen was built with Antigen.  You can install the entire source tree on your machine by downloading and running the Source Code Installer.  Like everything else, this was created from an Ant script wrapped by Antigen.



Adding optional Ant Tasks to the installer

By default the installer will include

though the option is given to remove these last two when you build your installer in order to reduce its size.



If you feel strongly that other tasks should be included by default please get in touch.



If you wish to include more jars in your installer then you have two options:

  • If using Maven to build your installer add the jars to the <dependencies> section of your project.xml file
  • If using Antigen to build the installer, you can enter additional jars if you check the 'Bundle additional jars into Installer' box. You will then be prompted to locate a directory containing these jars when the installer is built.